home *** CD-ROM | disk | FTP | other *** search
/ Scene 96 / Scene 96 International Edition (Zyklop Software) (Disc 2) (1997).iso / misc / coding / dos32xtn / docs.doc < prev    next >
Text File  |  1996-09-21  |  22KB  |  522 lines
  1.  
  2.  
  3.                        DOS32 EXTENTION PACKAGE FOR DJGPP
  4.  
  5.                                  Version 1.00
  6.  
  7.                             release date 21.9.1996
  8.  
  9.                        by rasputin aka Christian Lageman
  10.  
  11. Contents
  12. --------
  13.  
  14. I.   Legal stuff
  15. II.  How-to-use and how-it-works
  16. III. Memory model & technical stuff
  17. IV.  Removed and changed library functions
  18. V.   New functions & API
  19. VI.  New command line options
  20. VII. How to compile the sources
  21. VIII.Known bugs and problems
  22. IX.  Contact the author and get the original GNU stuff
  23. X.   Credits & greets
  24.  
  25.  
  26. I.  Legal stuff
  27. ---------------
  28. 1.  This package is distributed under the GNU General Public License and the
  29.     GNU Library General Public License of the Free Software Foundation.
  30.     (These licenses are in the files "copying" and "copying.lib")
  31. 2.  There is no warranty that any part of this package works or works the way
  32.     it is meant to be.
  33. 3.  The author isn't responsible for any damage caused by the use of this
  34.     package.
  35. 4.  Parts of this package have an different author than the author of this
  36.     package - they are distributed under the terms of their original authors
  37.     distribution license.
  38.     YOU MAY NOT MODIFY AND/OR REMOVE ANY COPYRIGHT NOTICES.
  39. 5.  The DOS32 package by Adam Seychell IS NOT PART OF THIS PACKAGE AND IT'S
  40.     LICENSE. It is distributed with this package only for legal reasons.
  41.  
  42. Some parts of this package are copyrighted by the following persons/institutions:
  43. DJ Delorie
  44. Adam Seychell
  45. CW Sandmann
  46. Eli Zaretskii
  47. Regents of the University of California
  48. Oleg Pliss
  49. Free Software Foundation
  50. all other people whose copyright notice you find in any file included in this
  51. package
  52.  
  53. II. How-to-use and how-it-works
  54. -------------------------------
  55. First install the libs (run me_1st!.exe to obtain infos about it).
  56. In  the new  dir  LIBDOS32 you  will  find the  library for DOS32,  in the  dir
  57. INCDOS32 the header files.
  58. To invoke  the DOS32 executable  output, just start the batch  swap.bat in  the
  59. DJGPP base  dir. It exchanges  the original  environment file  with a new  one,
  60. which contains different directories for the standard include and library files,
  61. so that the DOS32 libs and headers are used. This also changes the standard gcc
  62. output to DOS32  executables, because gcc  searches for the "specs" file in the
  63. standard  library dir,  so automatically  a new specs file  (which causes DOS32
  64. output) is used.
  65. If  you want  to link several  object files  to an executable  you can  use the
  66. dos32.lnk  linker script in  LIBDOS32 or the  linker  emulation  i386dos32. The
  67. emulation, however, WON'T work when you  link the standard DOS32 lib and crt0.o
  68. together  with  the  object  files  -  the  startup  code  depends  on  the
  69. djgpp_first_ctor etc. symbols  which are not created by the emulation (this was
  70. too library  specific to add  to the emulation). In  this case you will have to
  71. use the linker script.
  72. After linking the DOS32 executables don't have a stubloader. You'll have to call
  73. stubify to fix this. Gcc does  this automatically.  (Ok. One could convince the
  74. linker to do this, but in this case one would  also have to edit most makefiles
  75. for gcc and my main aim was to minimize such changes.)
  76.  
  77. If you want to produce a DOS32 dll,  you'll have to compile the involved source
  78. files to objects.  Then link them with the emulation i386dos32dll together. The
  79. output  will be a  plain DOS32 dll,  which can be loaded  via __dos32_load_dll.
  80. (No more dxegen. <g>)
  81. But always remember:
  82.      - DOS32 DLLs don't know anything about the main program.
  83.      - So, they can't use any variables or functions of the main program
  84.        directly.
  85.      - The __dos32_load_dll tries to zero out the region of memory, where
  86.        the DLL is loaded. But I'm not sure if DOS32 doesn't mess this up.
  87.        So, don't count on any bss var to contain zero.
  88.      - Avoid to use the standard libraries in the DLL. Many of them depend on
  89.        startup variables or drag in a lot of other functions.
  90.      - I haven't tested the dll option very extensively, it might be buggy.
  91.        (And, what makes it worse, the dll output is a quite dirty hack, what
  92.         makes bugs more likely.)
  93. So, the main use of dlls would be hardware drivers (p.e. video, sound) and
  94. similar stuff.
  95.  
  96. If you want to create go32-coffs files again, just call swap.bat - it will
  97. switch back to go32 output (and libs).
  98.  
  99. III. Memory model & technical stuff
  100. -----------------------------------
  101. Ok. I suppose you know the memory model of dos32. If not please read the dos32
  102. docs FIRST, otherwise you won't understand anything. (And I'm NOT going to
  103. explain the basic memory model of dos32.)
  104.  
  105. The main problem of DOS32 is, that it has a not very good normal memory
  106. allocation method (compared to other extenders). You can request memory only
  107. 64 times - this makes it unusable for malloc & co. So we must alloc all we need
  108. upon the start. This library has possible two ways to do this: a) you can
  109. specify the amount of memory which must remain free for other applications
  110. (default mode, with free memory zero) or b) you can specify the amount which
  111. your application allocates. DOS32 also provides a very nice function to alloc
  112. DMA buffers. However these functions will fail when called during run time and
  113. the application has already grapped all memory. So, I've included the feature
  114. that a certain number of DMA buffers can be alloced upon the start before any
  115. other memory is requested. (I strongly recommend to use always this method, even
  116. if there is enough memory for an DMA buffer - the free mem might be too bad
  117. located for an DMA buffer, crossing 64k boundaries or being shattered through
  118. the whole RAM.)
  119. The second, minor problem of DOS32 is that it's error output when an exception
  120. occurs is very bad. No registers, no exception address. By default the library
  121. uses it's own exception handlers, which dump out all infomation you need. DOS32,
  122. however, doesn't provide any exception handler functions or virtualizes the PIC,
  123. so that the lower IRQs and the exceptions 8-15 use the same interrupts. This
  124. forces an IRQ check in the exceptions handlers. The consequence is an additional
  125. slowdown (especially for handler 8), because my check method uses 5 port
  126. instructions (if you have a faster method -> mail me). You can switch off
  127. the exception handling for IRQ 8 or all IRQs by setting the corresponding crt0
  128. flags. An alternative is to link with noexcept.o, which has no exception
  129. handlers and therefore is about 1 kB smaller.
  130.  
  131.  
  132. IV.  Removed and changed library functions
  133. ------------------------------------------
  134. I had to remove some of the original library function, because they won't work
  135. under DOS32 or are obsolete. Programs which use these function must be updated.
  136. There are not so many important changed and removed functions, because I wanted
  137. to reduce the changes to a minimum. Most programs should run without or with
  138. only minimum changes.
  139.  
  140. Removed:
  141. brk & sbrk - our memory model has no "break" which can be moved, so I removed
  142.              them, although they could be easyly faked via __mem_top & __mem_max
  143.              (see malloc.c how to do this)
  144.  
  145. all dmpi functions - killed, DOS32 is no DPMI host, so we can't call any
  146.                      functions (although it has some similar functions)
  147. all go32 functions - killed, what extender are we using, he ?
  148.  
  149. intdos functions - different behavior, they contain a normal protected mode DOS
  150.                    int call, NOT an switch to realmode; the original
  151.                    "translated" functions are directly supported by dos32, so
  152.                    there was no use for the old code; this version supports a
  153.                    "translation" of some int 10h calls (font & string output).
  154.                    Intdosx calls are never translated, they just cause a normal
  155.                    int call. (guess why !)
  156.                    NOTE: The intdos calls could be in most cases replaced by
  157.                    assembler instruction templates (which I recommend).
  158.  
  159. bios functions - the maximum sectors read/write were changed to 16
  160.                  (a little less for extended sectors)
  161.  
  162. signal handling - This is the main negative side of this library: only the timer
  163.                   signal SIGALRM is supported. Signal handling for exceptions
  164.                   and IRQs would cause too much overhead and for "normal" ints
  165.                   it is not very useful. But my main reason not to support it
  166.                   was the fact that, there is nearly always a good workaround
  167.                   possible or the program can use its own faster methods.
  168.  
  169. crt0.h - some flag constants concering go32 and DPMI were removed
  170.  
  171. Many other functions were changed, too, but they should behave excatly the same
  172. like under go32. (If there is no bug.)
  173.  
  174.  
  175. V.   New functions & API
  176. ------------------------
  177. New vars and constants in crt0.h:
  178.  
  179. extern int _crt0_alloc_mem;
  180. This contains an memory size, the interpretation depends of _crt0_startup_flags.
  181. Default 0 (=if not defined by your program)
  182.  
  183. extern char _crt0_alloc_dma;
  184. Number of DMA buffers allocated on startup, maximum 8 (Want more ? Hey, there
  185. are only 8 DMA channels !), default 0 (=if not defined by your program)
  186.  
  187. These flags are the same as under go32:
  188. #define _CRT0_FLAG_PRESERVE_UPPER_CASE        0x0001
  189. #define _CRT0_FLAG_USE_DOS_SLASHES        0x0002
  190. #define _CRT0_FLAG_DROP_EXE_SUFFIX        0x0004
  191. #define _CRT0_FLAG_DROP_DRIVE_SPECIFIER    0x0008
  192. #define _CRT0_FLAG_DISALLOW_RESPONSE_FILES    0x0010
  193. #define _CRT0_FLAG_NO_LFN                       0x0400
  194.  
  195. New flags:
  196. #define _CRT0_FLAG_FILL_MEMORY 0x0020
  197. Fill all alloced memory upon the start. (not bss,only heap,bss is always set to
  198. zero)
  199.  
  200. #define _CRT0_FLAG_FILL_DEADBEEF        0x0040
  201. If set, fill memory (above) with 0xdeadbeef, else fill with zero.
  202. This is especially useful for debugging uninitialized memory problems. (???)
  203.  
  204.  
  205. #define _CRT0_FLAG_NO_EXCEPTION_AT_ALL  0x0800
  206. Don't install any exception handler, just rely on dos32. Same as linking with
  207. noexcept.o .
  208.  
  209. #define _CRT0_FLAG_NO_EXCEPTION_8       0x1000
  210. Don't install exception handler 8.
  211.  
  212. #define _CRT0_FLAG_ALLOC_MEM_CONTAINS_MIN 0x2000
  213. Defines how _crt0_alloc_mem is interpreted:
  214. If set it contains the amount memory which is alloced by the program
  215. (WARNING: in this case _crt0_alloc_mem should be > than 32 kB otherwise
  216.  the prog will abort/crash)
  217. If not set it contains the amount memory which must remain free. (Default)
  218.  
  219. #define _CRT0_FLAG_GRAP_ALL_MEM 0x4000
  220. Just graps all mem aviable - only one alloc call is used. I though this useful
  221. to avoid trouble when running the dos32 prog under go32 (p.e. stubify called by
  222. make;no memsize testing is made), but it doesn't solve the problems.
  223.  
  224. New types of <sys/cltypes.h>:
  225.  
  226. typedef unsigned short   _cl_selector;
  227. A selector.
  228. typedef unsigned short   _cl_segment;
  229. A real mode segment.
  230. typedef void *  _cl_flatptr;
  231. A flat pm ptr.
  232. typedef struct { unsigned long offset; unsigned short selector; } _cl_farptr;
  233. A protected mode far ptr.
  234. typedef struct {
  235. unsigned long offset;
  236. unsigned long selector;
  237. } _cl_large_farptr;
  238. A protected mode far ptr. (large version, sometimes needed for push/pop)
  239.  
  240. Vars and functions of dos32api.h:
  241.  
  242. extern unsigned long __dos32_prog_base;
  243. The base address of the program.
  244.  
  245. extern unsigned long __exe_length;
  246. The length of the exe file reported by dos32. (Additional data at the end of
  247. the executable isn't included, I think.)
  248.  
  249. extern _cl_flatptr   __psp_address;
  250. Flat address of the programs PSP. (normal DOS PSP, in low memory)
  251.  
  252. extern _cl_flatptr   __env_address;
  253. Flat address of the programs environment. (normal DOS environment, in low memory)
  254.  
  255. extern _cl_flatptr   __dos32_dos_buffer;
  256. Flat address of DOS32 8 Kb transfer buffer in low memory.
  257.  
  258. extern unsigned short __dos32_version;
  259. Version of DOS32, packed BCD.
  260.  
  261. extern _cl_selector  __dos32_ds;
  262. Programs data selector
  263.  
  264. extern _cl_selector  __dos32_cs;
  265. Programs code selector
  266.  
  267. extern _cl_selector  __dos32_zero;
  268. Zero base selector
  269.  
  270. extern _cl_segment   __dos32_dos_buffer_seg;
  271. DOS real mode segment of DOS32 transfer buffer.
  272.  
  273. extern unsigned char __dos32_system;
  274. The system DOS32 under which is running.
  275. Can have the following values:
  276. #define DOS32_SYSTEM_RAW_DOS 1
  277. #define DOS32_SYSTEM_XMS     2
  278. #define DOS32_SYSTEM_VCPI    4
  279. #define DOS32_SYSTEM_DPMI    8
  280.  
  281. extern _cl_flatptr   __vga_video_mem;
  282. Flat address of VGA video mem (at A0000).
  283.  
  284. extern _cl_flatptr   __primary_screen_address;
  285. Flat address of primary screen. (at B0000 or B8000)
  286.  
  287. extern _cl_flatptr   __secondary_screen_address;
  288. Flat address of secondary screen. (at B0000 or B8000)
  289.  
  290. typedef struct {
  291. unsigned long physical;  - physical address of DMA buffer
  292. _cl_flatptr   logical;   - flat address of DMA buffer
  293. } __dma_address_info;
  294.  
  295. extern __dma_address_info __dos32_prealloced_dma[8];
  296. This array contains the DMA channels allocated on startup.
  297.  
  298. #define __DOS32_DTA ((char *)__psp_address+0x80)
  299. The DTA is at the standard DTA in the PSP.
  300.  
  301. typedef struct {
  302. unsigned long    edi,esi,ebp,reserved,ebx,edx,ecx,eax;
  303. unsigned short   flags,es,ds,fs,gs,ip,cs,sp,ss;
  304. } _dos32_regs;
  305. Register struct for the real mode int and proc calls.
  306.  
  307.  
  308.  
  309. All these functions return !=0 if they fail, 0 on success
  310. extern int __dos32_get_dma_buffer(unsigned long *physical_address,void **block_address);
  311. Allocate a DMA buffer.
  312. extern int __dos32_free_dma_buffer(void);
  313. Free the last allocated DMA buffer. Warning ! This will mess up, if you call any
  314. DOS32 get DMA buffer / memory functions directly.
  315.  
  316. extern int __dos32_call_realmode_int(unsigned char number,_dos32_regs *regs,char flags);
  317. Call an real mode int.
  318. extern int __dos32_call_realmode_proc_retf(_dos32_regs *regs,char flags);
  319. Call an real mode proc with retf.
  320. extern int __dos32_call_realmode_proc_iret(_dos32_regs *regs,char flags);
  321. Call an real mode proc with iret.
  322.  
  323. These function can't fail:
  324. extern void __dos32_set_protect_mode_int_vec(char number,_cl_farptr *vector);
  325. Set a protected mode interrupt vector.
  326.  
  327. extern void __dos32_get_protect_mode_int_vec(char number,_cl_farptr *vector);
  328. Get a protected mode interrupt vector.
  329.  
  330. int __dos32_get_true_protect_mode_int_vec(char number,_cl_farptr *vector);
  331. Gets the original protected mode interrupt vector. (The vector of the interrupt
  332. that was installed before the startup code set up it's own handlers.)
  333. Returns 1, if the startup code has installed a different handler,  otherwise 0.
  334. BEWARE: This is only for chaining down to an original handler, if you want
  335.         the actual handler call the function above.
  336.  
  337.  
  338. /* these functions return 0 if they fail, otherwise an address */
  339. extern _cl_flatptr __dos32_set_physical_memory_mapping(unsigned long physical,unsigned long size);
  340. Sets a physical memory mapping and returns a flat address pointer to the start.
  341. extern long __dos32_get_iret_call_back(_cl_flatptr address);
  342. Requests an real mode iret call back for a protected mode proc.
  343. Returns an real mode (!) pointer to the call back.
  344. extern long __dos32_get_retf_call_back(_cl_flatptr address);
  345. Requests an real mode retf call back for a protected mode proc.
  346. Returns an real mode (!) pointer to the call back.
  347.  
  348. Macros for converting real mode adresses to flat.
  349. #define __real2linear(a) ((((a) & 0xffff0000U) >> 12)+((a) & 0xffffU))
  350. A real mode address to linear address.
  351. #define __real2flat(a)   (void *)(__real2linear(a)-__dos32_prog_base)
  352. A real mode address to flat protected mode address.
  353. #define __seg2linear(a)  ((a)<<4)
  354. A real mode segment to linear address.
  355. #define __seg2flat(a)    (void *)(__seg2linear(a)-__dos32_prog_base)
  356. A real mode segment to flat protected mode address.
  357.  
  358. This is the only function which remains of dpmi.h.
  359. void __dpmi_yield(void);
  360. This is a "release timeslice" call. Does nothing if no DPMI installed -> so
  361. I've included it.
  362.  
  363. The cbreak modes:
  364. #define DOS32_CBREAK_IGNORE 1 - ignore any <CTRL-BREAK> and <CTRL-C> presses
  365. #define DOS32_CBREAK_COUNT  2 - when ignoring, set an internal flag if
  366.                                 <CTRL-BREAK> is pressed
  367.  
  368. void __dos32_set_cbreak_mode(char mode);
  369. Set the cbreak mode.
  370. int  __dos32_cbreak_hit(void);
  371. Gets the state of the internal cbreak flag and sets it to zero.
  372.  
  373. long __dos32_load_dll(const char *name,const unsigned long dll_pos,
  374.                       void **entry_point,void **dll_start);
  375. This function loads a DOS32 dynamic link library.
  376. name    - filename of the dll.
  377. dll_pos - start of the dll in the file (this enables adding dlls to the exe
  378.           file)
  379. entry_point - a pointer where the entry point of the dll is stored
  380. dll_start   - a pointer where the start of the dll in mem is stored, you can
  381.               free the dll's memory with a simple free(dll_start).
  382. Returns:
  383. values>0 -> size of dll loaded
  384. values<0 one of the following errors
  385. #define DOS32_DLL_NO_MEM     -1  - no free memory for dll
  386. #define DOS32_DLL_FILE_ERROR -2  - error when accessing dll file
  387. #define DOS32_DLL_BAD_DLL    -3  - bad dll / file no dll
  388. #define DOS32_DLL_LOAD_ERROR -4  - error during loading of dll
  389.  
  390. VI.  New command line options
  391. -----------------------------
  392. For gcc (only when swap.bat enabled dos32 output via gcc)
  393.  -stackXXXXX
  394.  Same as -stack for ld, but no whitespace between switch and argument.
  395.  -stubXXXXXX
  396.  Same as -s for stubify.
  397. For ld.exe (the GNU linker)
  398.  -stack XXXXXX
  399.  Sets the stacksize of the executable (ignored for dlls). Default 64k
  400.  Minimum: 16k (?)
  401.  new emulations: i386dos32 , i386dos32dll
  402.  new targets: i386-dos32 , i386-dos32-dll
  403.  Warning these targets are for output ONLY. Using them as input targets will
  404.  cause ld to abort. So, don't set GNUTARGET to one of these.
  405. For stubify.exe:
  406.  -c
  407.  Compress the executable (only for DOS32).
  408.  -l
  409.  Show DOS32 logo when running the executable.
  410.  -sXXXXX
  411.  Uses a certain stubloader (not the default 225 bytes stub). -s without any
  412.  filename causes stubify to search dos32.exe on the path.
  413.  NOTE: stubify still handles coff output.
  414. For editd32.exe:
  415.  To get infos about the switch, run it without any arguments.
  416.  This program is used for changing the stubloader or compression of DOS32
  417.  executables.
  418.  
  419. VII. How to compile the sources
  420. -------------------------------
  421.  
  422. First decompress sources.zip with pkunzip -d in the djgpp base dir.
  423.  
  424. The library can be directly compiled by changing the directory to SCR\LIBDOS32
  425. and call makeall.bat. All sources should compile without problems if you use the
  426. standard directories. You might want to change the alignment of loops etc. in
  427. gcc.opt - I've set it to 2, because I think larger values it will increase
  428. significantly the size of the library but not its speed. (Most library functions
  429. aren't called soooo often and if you really, really, really want speed at any
  430. price - compile the sources files of the most important function with -S an
  431. optimize the asm code by hand)
  432.  
  433. To compile the linker you will need the original GNU linker sources. (ld version
  434. 2.5.2, bfd version 2.5)
  435. 1. Copy the files in SCR\NEWBFD to the bfd directory and the ones in SCR\NEWLD
  436.    ld source directory.
  437. 2. Run configur.bat in both source directories.
  438. 3. Make the liberty library.
  439. 4. Run make in the bfd directory.
  440. 5. Run make in the ld source directory.
  441. -> You have a brand new ld.exe.
  442.  
  443. NOTE: Due to the make bug of DOS32 (mentioned later in this documentation)
  444.       I strongly recommend that you compile editd32, stubify and ld as go32
  445.       executables. (ld won't compile as DOS32 anyway.)
  446.       For ld.exe you must "swap" (via swap.bat) back to DOS32 gcc output,
  447.       for stubify.exe and editd32.exe you must #-out the EXETARGET = DOS32
  448.       line in makefile.inc in SCR\LIBDOS32. (by default #-outed)
  449.  
  450. VII. Known bugs and problems
  451. ----------------------------
  452. 1. make bug:
  453.    Although most go32-applications run DOS32 files without problems (p.e. gcc),
  454.    when invoked by make the DOS32 application (p.e. stubify) fails to allocate
  455.    memory for the heap. I'm not sure whether this is a bug in make, DOS32 or
  456.    crt0.s - I haven't found any clues about it.
  457.    If you found solution -> mail me.
  458. 2. DOS32 zero write bug:
  459.    DOS32 itself has the bug that zero writes doesn't truncate the file a the
  460.    actual position, so the real mode int must be called in this cases.
  461. 3. Crash on no memory for DMA:
  462.    If there is no free memory and you request a DMA buffer the program crashes.
  463.    I dunno if this is caused by DOS32 or the program. I haven't tested this, it
  464.    did turn up only one time in crt0.
  465.  
  466. Other bugs:
  467. If you found an other bug, send me mail. But before you do that, make SURE THAT
  468. IT IS REALLY A BUG IN LIBC.A OR LD.EXE AND NOT IN YOUR PROGRAM.
  469. You can send me the solution to the bug, too. ;)
  470. I can't grantee that the library is 100% bug free. I've tested only a little
  471. and it is nearly impossible to test any situation for library anyway.
  472. I haven't tested if the library works with the c++ iostreams at all.
  473.  
  474.  
  475. VIII.Contact the author and get the original GNU stuff
  476. ------------------------------------------------------
  477. The author:
  478. FIDO: christian lageman@2:2490/4015.23  (preferred)
  479. EMAIL: cl@matrix.infox.com
  480. These addresses, however, might change in the near future.
  481.  
  482. You can also try it at:
  483. ECTO TRAXX 49-9504-678
  484. Leave a mail for rasputin or contact the sysop (e605).
  485.  
  486. If you need the original DJGPP or BINUTILS sources use one the the ftp sites
  487. in info.ftp or call Ecto Traxx and leave a mail to rasputin or the sysop.
  488.  
  489. IX.  Credits & greets
  490. ---------------------
  491.  
  492. Credits
  493. DJ Delorie
  494. CW Sandmann
  495. Adam Seychell
  496. Free Software Fountation
  497. for the rest see the legal stuff section
  498.  
  499. Greetz
  500. RR
  501. B2B
  502. E605
  503. SANCTION
  504. LD
  505. TRAN
  506. N-FACTOR
  507. CUBIC ^= DOJ
  508. FBK
  509. PURGE
  510. IMPHOBIA
  511. ORANGE
  512. NOOON
  513. BOMB20
  514. AMABLE
  515. SBR
  516. HBE
  517. ENERGETIC
  518. PHAT
  519. ZYKLOP
  520. UE
  521. rest of the world
  522.